Node / meshcore / MeshCore / files / docs / cli_commands.md

Displaying Rendered • View raw • Download

This document provides an overview of CLI commands that can be sent to MeshCore Repeaters, Room Servers and Sensors.

• Operational

• Neighbors

• Statistics

• Logging

• Information

• Configuration

• Radio

• System

• Routing

• ACL

• Region Management

• Region Examples

• GPS

• Sensors

• Bridge

• Ethernet

Usage:

• T383838reboot

Note: No reply is sent.

• T383838poweroff, or

• T383838shutdown

Note: No reply is sent.

• T383838clkreboot

Note: No reply is sent.

Usage:

• T383838clock sync

• T383838clock

Usage:

• T383838time <epoch_seconds>

• T383838epoch_seconds: Unix epoch time

Usage:

• T383838advert

• T383838advert.zerohop

• T383838start ota

• T383838erase

Serial Only: Yes

Warning: This is destructive!

Usage:

• T383838neighbors

Note: The output of this command is limited to the 8 most recent adverts.

Note: Each line is encoded as T383838{pubkey-prefix}:{timestamp}:{snr*4}

Usage:

• T383838neighbor.remove <pubkey_prefix>

Parameters:

• T383838pubkey_prefix: The public key of the node to remove from the neighbors list. This can be a short prefix or the full key. All neighbors matching the provided prefix will be removed.

Note: You can remove all neighbors by sending a space character as the prefix. The space indicates an empty prefix, which matches all existing neighbors.

Usage:

• T383838discover.neighbors

Usage: T383838clear stats

Usage:

• T383838stats-core

Serial Only: Yes

Usage: T383838stats-radio

Serial Only: Yes

Usage: T383838stats-packets

Serial Only: Yes

Usage: T383838log start

Usage: T383838log stop

Usage: T383838log erase

Usage: T383838log

Serial Only: Yes

Usage: T383838ver

Usage: T383838board

• T383838get radio

• T383838set radio <freq>,<bw>,<sf>,<cr>

• T383838freq: Frequency in MHz

• T383838bw: Bandwidth in kHz

• T383838sf: Spreading factor (5-12)

• T383838cr: Coding rate (5-8)

Set by build flag: T383838LORA_FREQ, T383838LORA_BW, T383838LORA_SF, T383838LORA_CR

Default: T383838869.525,250,11,5

Note: Requires reboot to apply

• T383838get tx

• T383838set tx <dbm>

• T383838dbm: Power level in dBm (1-22)

Set by build flag: T383838LORA_TX_POWER

Default: Varies by board

Notes: This setting only controls the power level of the LoRa chip. Some nodes have an additional power amplifier stage which increases the total output. Refer to the node's manual for the correct setting to use. Setting a value too high may violate the laws in your country.

Usage:

• T383838tempradio <freq>,<bw>,<sf>,<cr>,<timeout_mins>

• T383838freq: Frequency in MHz (300-2500)

• T383838bw: Bandwidth in kHz (7.8-500)

• T383838sf: Spreading factor (5-12)

• T383838cr: Coding rate (5-8)

• T383838timeout_mins: Duration in minutes (must be > 0)

Note: This is not saved to preferences and will clear on reboot

• T383838get freq

• T383838set freq <frequency>

• T383838frequency: Frequency in MHz

Default: T383838869.525

Note: Requires reboot to apply

Serial Only: T383838set freq <frequency>

• T383838get radio.rxgain

• T383838set radio.rxgain <state>

• T383838state: T383838on|T383838off

Default: T383838on

Temporary Note: If you upgraded from an older version to 1.14.1 without erasing flash, this setting is T383838off because of #2118

• T383838get radio.fem.rxgain

• T383838set radio.fem.rxgain <state>

• T383838state: T383838on|T383838off

• This controls the external LoRa FEM receive-path LNA where the board supports it.

• This is separate from T383838radio.rxgain, which controls the radio chip receive gain mode.

• T383838get name

• T383838set name <name>

• T383838name: Node name

Set by build flag: T383838ADVERT_NAME

Default: Varies by board

Note: Max length varies. If a location is set, the max length is 24 bytes; 32 otherwise. Emoji and unicode characters may take more than one byte.

• T383838get lat

• T383838set lat <degrees>

Set by build flag: T383838ADVERT_LAT

Default: T3838380

• T383838degrees: Latitude in degrees

• T383838get lon

• T383838set lon <degrees>

Set by build flag: T383838ADVERT_LON

Default: T3838380

• T383838degrees: Longitude in degrees

• T383838get prv.key

• T383838set prv.key <private_key>

• T383838private_key: Private key in hex format (64 hex characters)

• T383838get prv.key: Yes

• T383838set prv.key: No

Note: Requires reboot to take effect after setting

• T383838password <new_password>

• T383838new_password: New admin password

Set by build flag: T383838ADMIN_PASSWORD

Default: T383838password

Note: Command reply echoes the updated password for confirmation.

Note: Any node using this password will be added to the admin ACL list.

• T383838get guest.password

• T383838set guest.password <password>

• T383838password: Guest password

Set by build flag: T383838ROOM_PASSWORD (Room Server only)

Default: T383838<blank>

• T383838get owner.info

• T383838set owner.info <text>

• T383838text: Owner information text

Default: T383838<blank>

Note: T383838| characters are translated to newlines

Note: Requires firmware 1.12+

• T383838get adc.multiplier

• T383838set adc.multiplier <value>

• T383838value: ADC multiplier (0.0-10.0)

Default: T3838380.0 (value defined by board)

Note: Returns "Error: unsupported by this board" if hardware doesn't support it

Usage: T383838get public.key

Usage: T383838ver

Usage: T383838get role

• T383838powersaving

• T383838powersaving on

• T383838powersaving off

Parameters:

• T383838on: enable power saving

• T383838off: disable power saving

Default: T383838off

Note: When enabled, device enters sleep mode between radio transmissions

• T383838get repeat

• T383838set repeat <state>

• T383838state: T383838on|T383838off

Default: T383838on

• T383838get path.hash.mode

• T383838set path.hash.mode <value>

• T383838value: Path hash size (0-2)

• T3838380: 1 Byte hash size (256 unique ids)[64 max flood]

• T3838381: 2 Byte hash size (65,536 unique ids)[32 max flood]

• T3838382: 3 Byte hash size (16,777,216 unique ids)[21 max flood]

• T3838383: DO NOT USE (Reserved)

Default: T3838380

Note: the 'path.hash.mode' sets the low-level ID/hash encoding size used when the repeater adverts. This setting has no impact on what packet ID/hash size this repeater forwards, all sizes should be forwarded on firmware >= 1.14. This feature was added in firmware 1.14

Temporary Note: adverts with ID/hash sizes of 2 or 3 bytes may have limited flood propagation in your network while this feature is new as v1.13.0 firmware and older will drop packets with multibyte path ID/hashes as only 1-byte hashes are supported. Consider your install base of firmware >=1.14 has reached a criticality for effective network flooding before implementing higher ID/hash sizes.

• T383838get loop.detect

• T383838set loop.detect <state>

• T383838state:

• T383838off: no loop detection is performed

• T383838minimal: packets are dropped if repeater's ID/hash appears 4 or more times (1-byte), 2 or more (2-byte), 1 or more (3-byte)

• T383838moderate: packets are dropped if repeater's ID/hash appears 2 or more times (1-byte), 1 or more (2-byte), 1 or more (3-byte)

• T383838strict: packets are dropped if repeater's ID/hash appears 1 or more times (1-byte), 1 or more (2-byte), 1 or more (3-byte)

Default: T383838off

Note: When it is enabled, repeaters will now reject flood packets which look like they are in a loop. This has been happening recently in some meshes when there is just a single 'bad' repeater firmware out there (probably some forked or custom firmware). If the payload is messed with, then forwarded, the same packet ends up causing a packet storm, repeated up to the max 64 hops. This feature was added in firmware 1.14

Example: If preference is T383838loop.detect minimal, and a 1-byte path size packet is received, the repeater will see if its own ID/hash is already in the path. If it's already encoded 4 times, it will reject the packet. If the packet uses 2-byte path size, and repeater's own ID/hash is already encoded 2 times, it rejects. If the packet uses 3-byte path size, and the repeater's own ID/hash is already encoded 1 time, it rejects.

• T383838get txdelay

• T383838set txdelay <value>

• T383838value: Transmit delay factor (0-2)

Default: T3838380.5

Note: When multiple nearby repeaters all hear the same flood packet, each waits a random amount of time before retransmitting to avoid simultaneous collisions. This factor scales the size of that random window. Higher values reduce collision risk at the cost of added latency. T3838380 disables the window entirely.

• T383838get direct.txdelay

• T383838set direct.txdelay <value>

• T383838value: Direct transmit delay factor (0-2)

Default: T3838380.2

Note: Same collision-avoidance random window as T383838txdelay, but applied to direct (non-flood, routed) traffic. The default is lower because direct packets are addressed to a specific next hop, so far fewer nodes compete to retransmit them.

• T383838get rxdelay

• T383838set rxdelay <value>

• T383838value: Receive delay base (0-20)

Default: T3838380.0

Note: When enabled, repeaters that received a flood packet with a weak signal are held in a delay queue before processing, while those that received it with a strong signal process it immediately. This gives strong-signal paths forwarding priority. By the time weak-signal nodes process their copy, the packet may have already propagated and will be suppressed as a duplicate, reducing redundant retransmissions.

• T383838get dutycycle

• T383838set dutycycle <value>

• T383838value: Duty cycle percentage (1-100)

Default: T38383850% (equivalent to airtime factor 1.0)

• T383838set dutycycle 100 — no duty cycle limit

• T383838set dutycycle 50 — 50% duty cycle (default)

• T383838set dutycycle 10 — 10% duty cycle

• T383838set dutycycle 1 — 1% duty cycle (strictest EU requirement)

│ Note: Added in firmware v1.15.0

│ Deprecated as of firmware v1.15.0. Use get/set │ dutycycle

│ instead.

• T383838get af

• T383838set af <value>

• T383838value: Airtime factor (0-9). After each transmission, the repeater enforces a silent period of approximately the on-air transmission time multiplied by the value. This results in a long-term duty cycle of roughly 1 divided by (1 plus the value). For example:

• T383838af = 1 → ~50% duty

• T383838af = 2 → ~33% duty

• T383838af = 3 → ~25% duty

• T383838af = 9 → ~10% duty

You are responsible for choosing a value that is appropriate for your jurisdiction and channel plan (for example EU 868 Mhz 10% duty cycle regulation).

Default: T3838381.0

• T383838get int.thresh

• T383838set int.thresh <value>

• T383838value: Interference threshold value

Default: T3838380.0

• T383838get cad

• T383838set cad <on|off>

Description: When enabled, the radio performs a hardware Channel Activity Detection scan before transmitting and defers if the channel is busy. Runs independently of T383838int.thresh — either, both, or none may be active.

• T383838on|off: Enable or disable hardware CAD

Default: T383838off

• T383838get agc.reset.interval

• T383838set agc.reset.interval <value>

• T383838value: Interval in seconds rounded down to a multiple of 4 (17 becomes 16). 0 to disable.

Default: T3838380.0

• T383838get multi.acks

• T383838set multi.acks <state>

• T383838state: T3838380 (disable) or T3838381 (enable)

Default: T3838380

• T383838get flood.advert.interval

• T383838set flood.advert.interval <hours>

• T383838hours: Interval in hours (3-168)

Default: T38383812 (Repeater) - T3838380 (Sensor)

• T383838get advert.interval

• T383838set advert.interval <minutes>

• T383838minutes: Interval in minutes rounded down to the nearest multiple of 2 (61 becomes 60) (60-240)

Default: T3838380

• T383838get flood.max

• T383838set flood.max <value>

• T383838value: Maximum flood hop count (0-64)

Default: T38383864

• T383838get flood.max.unscoped

• T383838set flood.max.unscoped <value>

• T383838value: Maximum flood hop count (0-64) for a packet without a scope (no region set)

Default: T38383864 - (T3838380xFF indicates it hasn't been set, will track flood.max until it is.)

Note: An alternative to T383838region denyf *, setting T383838flood.max.unscoped to a lower value such as T3838383 would allow for local unscoped messages to propagate, while preventing noisy neighbors from flooding a local region.

• T383838get flood.max.advert

• T383838set flood.max.advert <value>

• T383838value: Maximum flood hop count (0-64) for an advert packet

Default: T3838388

Usage:

• T383838setperm <pubkey> <permissions>

• T383838pubkey: Companion public key

• T383838permissions:

• T3838380: Guest

• T3838381: Read-only

• T3838382: Read-write

• T3838383: Admin

Note: Removes the entry when T383838permissions is omitted

Usage:

• T383838get acl

Serial Only: Yes

• T383838get allow.read.only

• T383838set allow.read.only <state>

• T383838state: T383838on (enable) or T383838off (disable)

Default: T383838off

Usage:

• T383838region load

• T383838region load <name> [flood_flag]

• T383838name: A name of a region. T383838* represents the wildcard region

Note: T383838flood_flag: Optional T383838F to allow flooding

Note: Indentation creates parent-child relationships (max 8 levels)

Note: T383838region load with an empty name will not work remotely (it's interactive)

Usage:

• T383838region save

Usage:

• T383838region allowf <name>

Parameters:

• T383838name: Region name (or T383838* for wildcard)

Note: Setting on wildcard T383838* allows packets without region transport codes

Usage:

• T383838region denyf <name>

Parameters:

• T383838name: Region name (or T383838* for wildcard)

Note: Setting on wildcard T383838* drops packets without region transport codes

Usage:

• T383838region get <name>

• T383838name: Region name (or T383838* for wildcard)

Usage:

• T383838region home

• T383838region home <name>

• T383838name: Region name

Usage:

• T383838region default

• T383838region default {name|<null>}

• T383838name: Region name, or <null> to reset/clear

Usage:

• T383838region put <name> [parent_name]

• T383838name: Region name

• T383838parent_name: Parent region name (optional, defaults to wildcard)

• T383838region def <token> [<token> ...]

Parameters (tokens): Space-separated. A logical cursor starts at the wildcard T383838*.

• T383838name — Create T383838name as a child of the current cursor (equivalent to T383838region put name with the cursor as parent). Cursor moves to T383838name.

• T383838name|jump (or T383838name,jump) — Create T383838name as a child of the current cursor, then move the cursor to T383838jump (must already exist on the node, or have been created earlier in this command). T383838jump is not the parent of T383838name; use this form to pop back up and start another branch.

Behavior: Each created region defaults to flood-allowed (same as T383838region put). The reply is the resulting region tree (same format as bare T383838region); review it before running T383838region save to persist. On error, the reply is T383838Err - ... and any regions placed before the failure remain on the node, just like a partial chain of T383838region put.

Existing regions: T383838region def does not clear the existing tree — if a name already exists, its parent is updated to the current cursor; otherwise a new region is created. To start from scratch, T383838region remove the unwanted regions first.

Limits: Repeater serial accepts one line up to 160 characters. For larger trees, split across multiple T383838region def commands; the cursor resets to T383838* between commands, so lead the next command with T383838child|ancestor to reposition. Each token splits at most once on T383838| — T383838region def a|b|c|d is not a flat-list shorthand; see the flat-list example below.

Example — linear chain (each token becomes a child of the previous):

T282828

Example — branched tree (equivalent to T383838region put a, T383838region put b a, T383838region put c b, T383838region put d c, T383838region put e b, T383838region put f e):

T282828

T282828

The reply is T383838Err - unknown jump: nope. T383838a, T383838b, and T383838c were placed before the failure; T383838d was not. Run T383838region to inspect, then re-run with a corrected jump or repair with T383838region remove / T383838region put.

Example — flat list (each region a child of T383838*). Use T383838|* after each token to pop the cursor back to the root before the next token:

T282828

Usage:

• T383838region remove <name>

• T383838name: Region name

Note: Must remove all child regions before the region can be removed

Usage:

• T383838region list <filter>

Serial Only: Yes

• T383838filter: T383838allowed|T383838denied

Note: Requires firmware 1.12+

Usage:

• T383838region

Serial Only: For firmware older than 1.12.0

T282828

• Creates a region named T383838#Europe with flooding enabled

• Packets from this region will be flooded to other nodes

T282828

• Creates a wildcard region T383838* with flooding enabled

• Enables flooding for all regions automatically

• Applies only to packets without transport codes

T282828

• Creates a wildcard region T383838* without flooding

• This region exists but doesn't affect packet distribution

• Used as a default/empty region

T282828

• Creates T383838#Europe region with flooding enabled

• Adds nested child regions (T383838#UK, T383838#France)

• All nested regions inherit the flooding flag from parent

T282828

• Creates wildcard region T383838* with flooding enabled

• Adds nested T383838#NorthAmerica hierarchy

• Enables flooding for all child regions automatically

• Useful for global networks with specific regional rules

• T383838gps

• T383838gps <state>

• T383838state: T383838on|T383838off

Default: T383838off

Note: Output format:

• T383838off when the GPS hardware is disabled

• T383838on, {active|deactivated}, {fix|no fix}, {sat count} sats when the GPS hardware is enabled

Usage:

• T383838gps sync

Usage:

• T383838gps setloc

• T383838gps advert

• T383838gps advert <policy>

Parameters:

• T383838policy: T383838none|T383838share|T383838prefs

• T383838none: don't include location in adverts

• T383838share: share gps location (from SensorManager)

• T383838prefs: location stored in node's lat and lon settings

Default: T383838prefs

Usage: T383838sensor list [start]

• T383838start: Optional starting index (defaults to 0)

Note: Output format: T383838<var_name>=<value>\n

Usage:

• T383838sensor get <key>

• T383838sensor set <key> <value>

• T383838key: Sensor setting name

• T383838value: The value to set the sensor to

Usage: T383838get bridge.type

• T383838get bridge.enabled

• T383838set bridge.enabled <state>

• T383838state: T383838on|T383838off

Default: T383838off

• T383838get bridge.delay

• T383838set bridge.delay <ms>

• T383838ms: Delay in milliseconds (0-10000)

Default: T383838500

• T383838get bridge.source

• T383838set bridge.source <source>

• T383838source:

• T383838logRx: bridges received packets

• T383838logTx: bridges transmitted packets

Default: T383838logTx

• T383838get bridge.baud

• T383838set bridge.baud <rate>

• T383838rate: Baud rate (T3838389600, T38383819200, T38383838400, T38383857600, or T383838115200)

Default: T383838115200

• T383838get bridge.channel

• T383838set bridge.channel <channel>

• T383838channel: Channel number (1-14)

Usage:

• T383838get bridge.secret

• T383838set bridge.secret <secret>

• T383838secret: ESP-NOW bridge secret, up to 15 characters

Default: Varies by board

Usage: T383838get bootloader.ver

Usage: T383838get pwrmgt.support

Usage: T383838get pwrmgt.source

Note: Returns an error on boards without power management support.

Usage: T383838get pwrmgt.bootreason

Note: Returns an error on boards without power management support.

Usage: T383838get pwrmgt.bootmv

Note: Returns an error on boards without power management support.

Ethernet support is available on RAK4631 boards with a RAK13800 (W5100S) Ethernet module. Use the T383838_ethernet firmware variants (e.g. T383838RAK_4631_repeater_ethernet) to enable this feature.

• T383838eth.status

• T383838ETH: <ip>:<port> when connected (e.g. T383838ETH: 192.168.1.50:23)

• T383838ETH: not connected when Ethernet is not active

• Available on repeater and room server firmware only. Companion radio ethernet firmware does not expose a CLI.

• The Ethernet interface obtains an IP address via DHCP automatically on boot.

• A TCP server listens on port 23 (default) for CLI connections.

• Connect with any TCP client (e.g. T383838nc, PuTTY) to access the same CLI available over serial.